Step Forms
A Step Form is attached to a guide step as part of the data-entry feature. Data recorded from these forms may be accessed via the Work Log endpoints.
GET /step_forms/stepid/{stepid}
Get metadata on a Step Form for a step with a known stepid. Data on Step Form Fields includes field_guid. This is a string that will remain the same between revisions of the same field. This allows old data to be correlated with new data after a modification is made to a form, since the field_revisionid changes, but the field_guid does not. Also listed is the field_type. This can be one of 'Text Input', 'Text Area', 'Numeric Input', 'Checkbox', 'Radios', 'Select', 'Image', 'Video', or 'Document'. Text Inputs use the 'placeholder' field and ignore the 'textarea' field. Text Areas use the 'textarea' field and ignore the 'placeholder' field. Checkboxes default to a checked state when 'placeholder' is '1'. Text Areas may include line breaks, while Text Inputs may not. 'options' holds JSON representing an array of options.
Query Parameters
- guide_revisionid — Optional — integer
-
Look up a form at a specific version of a guide. Work Log entries list the guide_revisionid at time of creation. See Work Log API documentation for more information. If guide_revisionid is not present then this endpoint will default to returning the latest published version of the form.
- max_form_revisionid — Optional — integer
-
** DEPRECATED ** Please use guide_revisionid parameter instead. Using max_form_revisionid could result in draft changes being returned. If used then this endpoint will return a form with a form_revisionid less than or equal to max_form_revisionid. Work Log entries list the max_form_revisionid at time of creation, but this is no longer the standard way to query Step Forms.
Response
Status: 200 OK
{ "stepid": 420, "form_revisionid": 50, "date": 1387309230, "fields": [ { "field_revisionid": 111, "form_revisionid": 50, "field_guid": "field_did_part_fail_420_tue_sep_10_2013_10_45_14_gmt_0500_cdt_0_32179366098716855", "field_type": "Text Input", "required": true, "placeholder": ".02\"", "textarea": null, "label": "What was the tolerance for part ", "orderby": 0, "options": null }, { "field_revisionid": 112, "form_revisionid": 50, "field_guid": "field_what_was_the_temp_420_tue_nov_26_2013_13_22_29_gmt_0800_pst_0_03242474305443466", "field_type": "Text Area", "required": true, "placeholder": null, "textarea": "200 to 400 ", "label": "What was the temp", "orderby": 1, "options": null }, { "field_revisionid": 113, "form_revisionid": 50, "field_guid": "field_what_failed_420_wed_oct_30_2013_14_11_50_gmt_0500_cdt_0_792655361816287", "field_type": "Text Input", "required": true, "placeholder": "part a", "textarea": null, "label": "what failed?", "orderby": 2, "options": null }, { "field_revisionid": 114, "form_revisionid": 50, "field_guid": "field_what_was_the_runout_420_fri_nov_01_2013_10_20_38_gmt_0700_pdt_0_04374332004226744", "field_type": "Text Input", "required": true, "placeholder": ".01 to .04", "textarea": null, "label": "What was the runout?", "orderby": 3, "options": null }, { "field_revisionid": 115, "form_revisionid": 50, "field_guid": "field_which_side_was_damaged_420_fri_nov_01_2013_10_20_38_gmt_0700_pdt_0_04374332004226745", "field_type": "Select", "required": false, "placeholder": null, "textarea": null, "label": "Which side was damaged?", "orderby": 4, "options": [ "Left Side", "Right Side" ] }, { "field_revisionid": 116, "form_revisionid": 50, "field_guid": "field_height_420_fri_nov_01_2013_10_20_38_gmt_0700_pdt_0_04374332004226745", "field_type": "Numeric Input", "required": false, "placeholder": 200, "textarea": null, "label": "Height in mm", "orderby": 5, "options": { "limit_decimals": true, "decimals": 0, "limit_min": true, "min": 0, "limit_max": true, "max": 100 } }, { "field_revisionid": 117, "form_revisionid": 50, "field_guid": "field_which_side_was_damaged_420_fri_nov_01_2013_10_20_38_gmt_0700_pdt_0_04374332004226745", "field_type": "Radios", "required": true, "placeholder": null, "textarea": null, "label": "Which side was damaged?", "orderby": 6, "options": [ "Left Side", "Right Side" ] }, { "field_revisionid": 118, "form_revisionid": 50, "field_guid": "field_image_420_fri_nov_01_2013_10_20_38_gmt_0700_pdt_0_04374332004226745", "field_type": "Image", "required": false, "placeholder": null, "textarea": null, "label": "Image of part", "orderby": 7, "options": null } ] }
GET /step_forms/form_revisionid/{form_revisionid}
Get metadata on a Step Form with a known form_revisionid. See detailed description at GET /step_forms/stepid/{stepid}.
Response
Status: 200 OK
{ "stepid": 420, "form_revisionid": 50, "date": 1387309230, "fields": [ { "field_revisionid": 111, "form_revisionid": 50, "field_guid": "field_did_part_fail_420_tue_sep_10_2013_10_45_14_gmt_0500_cdt_0_32179366098716855", "field_type": "Text Input", "required": true, "placeholder": ".02\"", "textarea": null, "label": "What was the tolerance for part ", "orderby": 0, "options": null }, { "field_revisionid": 112, "form_revisionid": 50, "field_guid": "field_what_was_the_temp_420_tue_nov_26_2013_13_22_29_gmt_0800_pst_0_03242474305443466", "field_type": "Text Area", "required": true, "placeholder": null, "textarea": "200 to 400 ", "label": "What was the temp", "orderby": 1, "options": null }, { "field_revisionid": 113, "form_revisionid": 50, "field_guid": "field_what_failed_420_wed_oct_30_2013_14_11_50_gmt_0500_cdt_0_792655361816287", "field_type": "Text Input", "required": true, "placeholder": "part a", "textarea": null, "label": "what failed?", "orderby": 2, "options": null }, { "field_revisionid": 114, "form_revisionid": 50, "field_guid": "field_what_was_the_runout_420_fri_nov_01_2013_10_20_38_gmt_0700_pdt_0_04374332004226744", "field_type": "Text Input", "required": true, "placeholder": ".01 to .04", "textarea": null, "label": "What was the runout?", "orderby": 3, "options": null } ] }
GET /step_forms/field_revisionid/{field_revisionid}
Get metadata on a Step Form containing a field with a known field_revisionid. See detailed description at GET /step_forms/stepid/{stepid}. This may be useful when examining old Work Log data, since that data may be keyed on field_revisionid. Multiple field_revisionids may give the same response, since a form may have multiple fields.
Response
Status: 200 OK
{ "stepid": 420, "form_revisionid": 50, "date": 1387309230, "fields": [ { "field_revisionid": 111, "form_revisionid": 50, "field_guid": "field_did_part_fail_420_tue_sep_10_2013_10_45_14_gmt_0500_cdt_0_32179366098716855", "field_type": "Text Input", "required": true, "placeholder": ".02\"", "textarea": null, "label": "What was the tolerance for part ", "orderby": 0, "options": null }, { "field_revisionid": 112, "form_revisionid": 50, "field_guid": "field_what_was_the_temp_420_tue_nov_26_2013_13_22_29_gmt_0800_pst_0_03242474305443466", "field_type": "Text Area", "required": true, "placeholder": null, "textarea": "200 to 400 ", "label": "What was the temp", "orderby": 1, "options": null }, { "field_revisionid": 113, "form_revisionid": 50, "field_guid": "field_what_failed_420_wed_oct_30_2013_14_11_50_gmt_0500_cdt_0_792655361816287", "field_type": "Text Input", "required": true, "placeholder": "part a", "textarea": null, "label": "what failed?", "orderby": 2, "options": null }, { "field_revisionid": 114, "form_revisionid": 50, "field_guid": "field_what_was_the_runout_420_fri_nov_01_2013_10_20_38_gmt_0700_pdt_0_04374332004226744", "field_type": "Text Input", "required": true, "placeholder": ".01 to .04", "textarea": null, "label": "What was the runout?", "orderby": 3, "options": null } ] }
GET /step_forms/guideid/{guideid}
Get metadata on a Step Form for all steps attached to a known guideid, including prerequisite guides. See detailed description at GET /step_forms/stepid/{stepid}. Note that ordering of forms is not guaranteed, and there may not be a form for each step.
Query Parameters
- guide_revisionid — Optional — integer
-
Look up the forms at a specific version of the guide. Work Log entries list the guide_revisionid at time of creation. See Work Log API documentation for more information. If guide_revisionid is not present then this endpoint will default to returning the latest published version of the forms.
- max_form_revisionid — Optional — integer
-
** DEPRECATED ** Please use guide_revisionid parameter instead. Using max_form_revisionid could result in draft changes being returned. If used then this endpoint will return forms with a form_revisionid less than or equal to max_form_revisionid. Work Log entries list the max_form_revisionid at time of creation, but this is no longer the standard way to query Step Forms.
Response
Status: 200 OK
{ "forms": [ { "stepid": 422, "form_revisionid": 30, "date": 1383322989, "fields": [ { "field_revisionid": 59, "form_revisionid": 30, "field_guid": "field_did_you_complete_this_operation_422_fri_nov_01_2013_11_23_08_gmt_0500_cdt_0_28500672499649227", "field_type": "Text Input", "required": true, "placeholder": "yes or no", "textarea": null, "label": "Did you complete this operation?", "orderby": 0, "options": null } ] }, { "stepid": 420, "form_revisionid": 50, "date": 1387309230, "fields": [ { "field_revisionid": 111, "form_revisionid": 50, "field_guid": "field_did_part_fail_420_tue_sep_10_2013_10_45_14_gmt_0500_cdt_0_32179366098716855", "field_type": "Text Input", "required": true, "placeholder": ".02\"", "textarea": null, "label": "What was the tolerance for part ", "orderby": 0, "options": null }, { "field_revisionid": 112, "form_revisionid": 50, "field_guid": "field_what_was_the_temp_420_tue_nov_26_2013_13_22_29_gmt_0800_pst_0_03242474305443466", "field_type": "Text Area", "required": true, "placeholder": null, "textarea": "200 to 400 ", "label": "What was the temp", "orderby": 1, "options": null }, { "field_revisionid": 113, "form_revisionid": 50, "field_guid": "field_what_failed_420_wed_oct_30_2013_14_11_50_gmt_0500_cdt_0_792655361816287", "field_type": "Text Input", "required": true, "placeholder": "part a", "textarea": null, "label": "what failed?", "orderby": 2, "options": null }, { "field_revisionid": 114, "form_revisionid": 50, "field_guid": "field_what_was_the_runout_420_fri_nov_01_2013_10_20_38_gmt_0700_pdt_0_04374332004226744", "field_type": "Text Input", "required": true, "placeholder": ".01 to .04", "textarea": null, "label": "What was the runout?", "orderby": 3, "options": null } ] } ] }
POST /step_forms/{stepid}
Save a new or updated Step Form to a given stepid. Not all fields must be supplied, but some fields are required with certain input types.
Request Body
- fields — Required — array of objects
-
Array of field objects that make up the form. Each object contains:
- field_type— Required. One of 'Checkbox', 'Text Input', 'Text Area', 'Numeric Input', 'Radios', 'Select', 'Image', 'Video', or 'Document'. A checkbox may be true or false. A text input may contain a single line of text, a text area may contain multiple lines of text, a numeric input may contain a number, a select may contain an array of strings as options.
- label— Required. Text that will display above a field when viewing a guide.
- field_guid— Required. Any unique string to identify this field. A good example is a creation timestamp concatenated with the label and type. This allows multiple field revisions to be correlated between revisions. If a field is being updated rather than inserted, the field_guid must match between revisions or the system will behave as though the field was deleted and recreated.
- placeholder— Optional. Must be specified when field_type is 'Checkbox' or 'Text Input'. When field_type is 'Checkbox', placeholder must be boolean true or false. When field_type is 'Text Input', placeholder must be a string with no line breaks. This string will apear in the empty text input before any text is entered.
- textarea— Optional. Must be specified when field_type is 'Text Area'. This string will appear in the empty text area before any text is entered. Multiple lines are allowed.
- required— Optional. Must be specified as true or false when field_type is 'Text Input' or 'Text Area'. Fields that are required will reject submission until they are filled. A checkbox cannot be required, since it always has a value.
- options— Optional. Must be specified when field_type is 'Select' or 'Radios'. This array will contain the options (as strings) to be selected from the dropdown. When field_type is Numeric Input, options must be an object with validation rules as shown in the example.
Response
Status: 201 Created
{ "stepid": "1171", "form_revisionid": 98, "date": 1429776581, "fields": [ { "field_revisionid": 297, "form_revisionid": 98, "field_guid": "field_i_completed_this_step_1171_fri_aug_01_2014_11_36_41_gmt_0700_pdt_0_21151212765835226", "field_type": "Checkbox", "required": null, "placeholder": true, "textarea": null, "label": "Example Checkbox Label", "orderby": 0, "options": null }, { "field_revisionid": 298, "form_revisionid": 98, "field_guid": "field_example_text_input_label_1171_thu_apr_23_2015_04_09_52_gmt_0400_edt_0_9165945767890662", "field_type": "Text Input", "required": true, "placeholder": "0.07", "textarea": null, "label": "Example Text Input Label", "orderby": 1, "options": null }, { "field_revisionid": 299, "form_revisionid": 98, "field_guid": "field_example_multi_line_text_area_label_1171_thu_apr_23_2015_04_09_52_gmt_0400_edt_0_03674075356684625", "field_type": "Text Area", "required": false, "placeholder": null, "textarea": "Default Text", "label": "Example Multi-line Text Area Label", "orderby": 2, "options": null }, { "field_revisionid": 300, "form_revisionid": 98, "field_guid": "field_which_side_was_damaged_420_fri_nov_01_2013_10_20_38_gmt_0700_pdt_0_04374332004226745", "field_type": "Select", "required": false, "placeholder": null, "textarea": null, "label": "Which side was damaged?", "orderby": 3, "options": [ "Left Side", "Right Side" ] }, { "field_revisionid": 301, "form_revisionid": 98, "field_guid": "field_example_numeric_input_label_1171_thu_apr_23_2015_04_10_52_gmt_0400_edt_0_9165945767220662", "field_type": "Numeric Input", "required": true, "placeholder": 200, "textarea": null, "label": "Height in mm", "orderby": 4, "options": { "limit_decimals": true, "decimals": 0, "limit_min": true, "min": 0, "limit_max": true, "max": 100 } }, { "field_revisionid": 300, "form_revisionid": 98, "field_guid": "field_which_side_was_damaged_420_fri_nov_01_2013_10_20_38_gmt_0700_pdt_0_04374332004226745", "field_type": "Radios", "required": true, "placeholder": null, "textarea": null, "label": "Which side was damaged?", "orderby": 5, "options": [ "Left Side", "Right Side" ] } ] }